GetOpt

Type

function

Summary

Parse options from command line arguments Associated:GetOptLibrary

Syntax

GetOpt(<grammar> [, <argumentArray>])

Description

Parse UNIX-like command line arguments, extracting options and their arguments.

The GetOpt function parses the command-line arguments. The optional parameter argumentArray is a numerically-keyed array containing the arguments to be parsed; if it is omitted, it is set to the commandArguments.

The grammar describes the possible options that GetOpt should understand. It is a string containing a series of option specifications, separated by spaces. Each option specification is a series of option names which should be treated as synonyms of each other, separated by commas. Single-character synonyms are treated as short (-h) options, and multi-character synonyms are treated as long (--help) options. Option names can't start with a - or contain =. The last synonym in each option specification is treated as the "proper" name of the option.

For example, h,help indicates that both -h and --help options are supported, and they are both properly known as the "help" option.

Each option specification can end with a =. This indicates that the option expects an argument. For example, with the grammar -o,--output=, the option can be specified like -o file, -ofile, --output file, or --output=file.

If a non-option argument is found in argumentArray, GetOpt stops parsing options and all subsequent arguments are returned as they are. - is always treated as a non-option argument. The special -- option ends option parsing, but is otherwise ignored. This makes it possible to pass filenames on the command line that are named the same as options. For example, -- --help will treat --help as a normal argument, not an option.

Short options can be run together. For example, if grammar is h,help v,verbose, then -hv is treated as if both --help and --verbose were passed as options to the command.

If an option is specified more than once, only the last occurrence is reflected in the return value of GetOpt

The return value of GetOpt is an array with three keys:

• "options": an array where the keys are option names and the values are the arguments to those options.
• "arguments": a numerically-indexed array where the values are the non-option arguments
• "errors": a numerically-indexed array where the values are error messages from GetOpt's processing of the argumentArray

Argument processing errors occur if:

• an option is found that wasn't in the < grammar:::note[ an option has an argument, but the grammar says it shouldn't ]

an option doesn't have an argument, but the grammar says it should

:::

Parameters

Name	Type	Description
grammar		A string describing the valid options for the program
argumentArray		A numerically keyed array containing arguments to be parsed

Examples

local tInfo
put GetOpt("h,help") into tInfo
if the number of elements in tInfo["errors"] > 0 then
   write "ERROR:" && tInfo["errors"][1] to stderr
else if "help" is among the keys of tInfo["options"] then
   write "Usage: my-program [--help]" to stderr
end if